ZX FTP client, ver. 1.0- instructions
*************************************

FOREWORD
********

Dear Wifi users, with big happinnes and proudness in my heart, I present to the ZX world one of the first FTP clients for ZX Spectrum. It took me 13 months of ceaseless work so far. The result is quite satisfying. I regard it is probably the most useful program I have written for ZX Spectrum so far.

Previous public version 0.7 was not able to display and browse directory content. Version 1.0 can do it now.

I designed version 1.0 in a way, so that it can be ported to another hw configuration most easily. In version 1.0, I may only fix bugs or add something minor but do not plan to extend it anymore. Instead, I plan next versions specially bound to eLeMeNt ZX and MB03+ Ultimate (www.128land.com) hardware to make the client better. So if you are interested in porting version 1.0 to another ZX system, version 1.0 is practically the best (and only) starting point. In that case, just ask me for details.

Version 1.0 is able to run on ZXS 48K. It has only tens of bytes free space, but I want to keep it for bug fixing.

The main code of the client uses latest Wifi Bios ver 1.8. and Speed Management 2.0. The Bios ensures low level routines and the Bios as well as Speed Management 2.0 can be used independently in other applications too. Both make it easier for wifi coder to code their programs.

The source code consists of extra sources: binary font, keyboard and print source, keyboard read routine by Busy and disk opeartion sources for easier porting to another disk systems.

If porting, keep in mind, that the wifi device we use is placed in MB03+, it is ESP-01 module, the same one as was used in first batch of ZX Next. Writing your own wifi bios for your wifi hw would be the easiest option to port the client to hw of your favour. Recently, also eLeMeNt ZX has been fitted with a bit more modern wifi module, so the client should be able to work also without MB03+ interface.

Version 1.0 exists in two variants. The differ in disk system support. The first is for BS-DOS, the second for Esxdos. So I guess the later will be mostly used as Esxdos users are many. About disk operations later on.


REQUIREMENTS
************
- MB03+ interface fitted with Wifi module ESP-01
- BSDOS disk operating system
- eLeMeNt ZX clone- fitted with Wifi module ESP-01


MAIN FEATURES
*************
Version 1.0 is ideal for downloading and uploading ZX programms between FTP server and your ZX computer, without need of removing your memory card. It also enables you to organise directories and files on the FTP server.


FEATURES
********
- it can connect to local, remote as well as mobile ftp servers
- it useses 20 ftp commands (previous release 0.7 had 10)
- it uses command prompt for you to write other commands directly to the server
- display and browse directory
- mark files
- find files
- upload one file
- download multiple files
- create directory
- rename files/ directories
- delete files/ empty directories
- maximum items that the directory is able to hold up is roughly 500- 1200 items



ZX MEMORY
*********
Version 1.0 executive code starts from #C800 (51200). It also uses buffer memory from #6000 to #C7FF which is used for upload and download files and for directory. Since this memory is shared, directory has to be reread each time after file has been up/downloaded. Executive memory could be extended, but only at a cost of diminshing buffer memory, which would result in less place for directory items. Stack pointer starts at #6000 and goes down. For multiple item operations, memory from #4800- #4FFF is in use too.


CONTROL KEYS
************
Control keys can be divided into 2 groups. First group is controls 1) without directory read, second group of keys 2) controls for directory operation.

1)- general control keys
- F- file: 	allows user to enter their default file name which will be downloaded always when pressing SS+D
- T- start:	allows user to enter their default start address for files being downloaded (not applicable to Esxdos)
- A- autologin:	select if automatic login should be carried out upon client start
- H- host:	select your ftp server URL
- E- usr:	enter ftp server user
- P- pass:	enter ftp server password
- SS+P:		show/hide displayed password
- U- upl:	upload file, enter its name
- S- size:	returns item size, enter its name
- Q- quit:	quit client (ftp connection remains up)
- W- wifi:	on/off. Sets your wifi state upon client quit
- L- login	login to ftp server, user and password will be entered manually
- SS+L		login to ftp server, user and password are taken from variables
- O- logoff	logg of ftp server
- V- savApp	save application with its settings and variables
- D- dwnld	download file/s
- ss+D		download file, name and start address taken form variables
- CS+D		download file, name entered manually
- C- com	enter ftp command

2)- directory control keys
- I- Fn		find item
- Spc		space- un/mark item
- Z,X		roll directory item if it is longer than screen
- R- Rr		reread directory
- 6- Rn		rename item
- 7- MD		make new directory
- Del		delete item/s
- Br- UD	break key, jump up directory
- N		change way of directory retrieve (NLST/ LIST)
- ss+N		read directory abbreviated or full
- Enter		enter directory
- arrows	up/down for browse directory up/down or left/ right for page up/down

In the course of your work, where available, use B key to abort action.


SCREEN ORGANISATION
*******************
The screen can be divided into 3 parts. Upper, middle and lower.

Upper part.
- line 1,2	Author+ version number, or directory path.
- line 3	Speed: speed info (default is 16, which is max), speed cannot be changed
		Logged in: OK for being logged in, X the opposite
		STATUS: 2- module connected to AP and IP is obtained
			3- TCP transmission created (this is the state you want)
			4- TC transmission disconnected
			5- module is not connected to AP (Acess Point) at all
- line 4	Host: shows URL of your ftp server, or X if not connected
- line 5,6,7	answers from FTP server

Middle part
- line 8-15	FTP directory

Lower part
- line 16	related to FTP directory.
			showing number of items/ directories/ files
			directory control keys
- line 17:	File: variable file name, that the user can change.
		Start: variable start address for downloaded file, that the user can change
- line 18:	Host: variable host name, that the user can change
		User: user name for login, that the user can change
		Pass: password for login, that the user can change
- line 19,20:	general control keys
- line 21:	number of marked files
		directory retrieve mode (LIST/NLST/full/abbr)
- line 23:	info line guiding the user throughout their action
- line 24:	input line


INPUT LINE FEATURES
*******************
Throughout your work input prompt line apperas on the screen. The input line uses these keys:
- left/right- for moving your cursor
- TRUE VIDEO- for input abort
- DELETE
- GRAPH- for backspace
- SS+Q- for jump on line start


SETUP
*****
There is no setup or configuration file for the moment. ZX FTP client works as a single machine code file (on MB03+) or a .TAP file (on Esxdos). The reason is, that on BS-DOS you will be able to run it from a remote path (using eg. NEW#3,25 command, meaning "run file number 25 from disk 3). More info on how to handle setup, see below in disk operations section.


LOGGING IN
**********
The client has quite convenient way of logging in to ftp server. First of all, the client contains host url, user and password variables, which the user can change. At the same time, you can set auto login variable with A key. If set to yes, the client performs automatic login to ftp server. If set to no, it does not.


SERVERS
*******
Communicating with server is probably the trickiest part of the whole client. Different server types and setting or restrictions can make it impossible or hard to access such servers. The client should be able to access any ftp server in the world, including mobile phone ftp servers, which do not operate on port 21 (standart ftp port), but on a different ports. ON ZX Spectrum, we are quite dependent on the server as 8 bit ZXS does not have enough power to organise obtained data much. Theoretically, any ftp server can behave in a different way. If you run upon the server, of which data the client processes badly, let me know.

In case your server is a standart one (ie. it uses standart FTP port 21), just enter it with key H in normal way. Like "192.168.0.200", or "hood.speccy.cz". If your server uses different port (eg. 31546), enter its URL like this: "192.168.0.200:31546", or "hood.speccy.cz:31546".


DIRECTORY
*********
I think, work with directory should be the essence of the FTP client. Although we are quite limited with ZXS possibilities how to process incoming directory data. Out of the few servers I tried, all of them returned directory items (be it directory or file) in alphabetical order, which is a nice feature for the user. I found no way, how the client could make the server send data in a way the client dictates. Almost all servers I tested did not distinguish between directory and file. All were just items. It means, directories starting with eg. Z letter were sent at the end of directory list. The only one exception were mobile phone servers, some of them returned directories first, and then files- all in alphabetical order, which, I believe, is an ideal. Organising items in different way would require very sophisticated routines on ZX side, more memory and long waiting time. I think, we can forget about it for the moment.


WORKING WITH DIRECTORY
**********************
Directory is closesly bound with memory. The free memory for directory is #6800 bytes (26624 in decimal). It often happens this is not enough even for ZX files to hold them all. If the memory has run out of memory during directory retrieve, the client will show a message "Transfer incomplete". Then there is an information about number of directories or files or items stored in your memory displayed just a line below directory itself.

Retrieving directory can be done in 3 modes (see ss/+N control):
1) LIST full
LIST is an ftp command that returns complete items (like: attributes, owner, date, time, length, etc.).  This mode brings you all the data. Use this mode only in case other modes fail you, it shows you the way the server returns the directory. In this mode the client cannot work, since the data can varry a great deal. Some example could look like this:
-rw-r--r-- 1 ftp ftp          27582 Feb 03  2022 03.lim
-rw-r--r-- 1 ftp ftp          30913 Feb 03  2022 03.scr
drw-r--r-- 1 ftp ftp          22445 Feb 03  2022 04
-rw-r--r-- 1 ftp ftp          30913 Feb 03  2022 04.scr

2) LIST abbr
same as mode 1, but redundant data will be removed this time, meaning ZX memory can hold more items. Directories start always with "D" at the line start. This is the default mode and could look like this:
       27582 Feb 03  2022 03.lim
       30913 Feb 03  2022 03.scr
D      22445 Feb 03  2022 04
       30913 Feb 03  2022 04.scr

3) NLST full
NLST is an ftp command and it returns item names only. For us this is the most economical way of storing items. This mode is always reliable, but you cannot differ between a directory and a file, that's why I reffer to them as items. However, entering an item that may look like dir, the client will try and if it is directory, it should not fail. The output looks like this:
03.lim
03.scr
04
04.scr

It can happen, one directory entry is longer than the whole screen. You recognise such an entry by two ending dots. In this case, press "X" and "Z" to roll through the item to see it complete.


DELETING DIRECTORY
******************
If the directory is empty, there is no issue deleting it. If not empty, FTP refuses to do it. The directory have to be entered, all items marked and deleted. However, in version 1.0 you have to do it manually. There is a lack of memory for such action.


JUMPING FROM DIRECTORY
**********************
You can either move the cursor to the very first item in the directory ".." and press enter, or more convenient, press break key at any time, it does the same.


MARKING ITEMS
*************
With the space key, you can mark or unmark files. Other ways of marking files is with find function, see below. Un/mark all is not supported in version 1.0. As for marking files, there is an Easter egg hidden for you. Are you able to reveal it?


FIND
****
This is very useful function, lifting the client a level higher at only several bytes cost. You may enter any kind of string, the client will look up the item name for you in the directory. Matching items are highlithed in red and their number will be displayed on the third bottom line. At the same time you will be transfered to the first matching item. Find function is case insensitive. If you enter just one letter, all items starting with this letter will be found- this is very useful, if you just need to move to certain letter in the directory file list. Found items will become marked items.

Let's say you want to find all tap files. Simply enter ".tap" and all matching files will be highlighted for you.  


UPLOAD
******
In version 1.0 as opposed to the previous 0.7 I added STOU command upon which the server creates a new file in case the name already exists. Press U, enter file name from your disk and upload will start. Speed is around 3 kb/ sec.


DOWNLOAD
********
There are 3 was of how to download file.

SS+D= download file from file name variable and assign it with start address from the variable. This is very handy when you eg. need to test one file (eg. you are writing an executive code on PC) and want to download it all the time.

CS+D= enter file name you want to download manually.

D= download file under cursor. If there are marked files, than the one under your cursor will be ignored and all marked files will be downloaded.

Download speed using 20 Mhz CPU should be up to 60 kb/sec (depending on ftp the server).


DISK OPERATIONS
***************
You will find two disk versions of the client in the package. The first one is for BS-DOS, and the second one for Esxdos.

The first version runs on MB03+ interface with BS-DOS. It originated in 1996 and was written by Slavo Labsky, known as Busy, introduced in MB-02+ hardware, the predecessor of MB03+. This is still my main disk system, I am using it 90% when sitting at Speccy. The client is just one machine code file which can be run with NEW command. It means if you want to upload or download files from/ to your favourite destination, just navigate yourself to that destination from Basic and run the client with usuual "NEW#disk_number,ftp_client_file_number" and your path remains unchanged. In order to navigate through your disks and directories more happilly, use my nmi menu, which enables to change disks and directories with keys O and P. If the file being downloaded already exists on the disc, this presents no obstacle for BS-DOS. It can hold hundreds of files carrying the same name.

The setup file is saved as a single machine code file as well.

Similarly, in Esxdos, you will have to navigate through your source/ destination path using nmi menu, quite easily.

Uploading files from your Speccy to FTP server is the same for both systems. Press U to enter the name of the file in your current disc location which you wish to upload, and it will be read from your disc and uploaded to the ftp server to the path you have opened.

In download, files travel the oposite way. While on BS-DOS, same name files are no issue, on Esxdos, if the file being downloaded already exists on your destination disc, its name will be automatically rewritten in its last 4 positions. Eg. file "manicmin.tap" will be renamed "mani#001.tap", then "mani#002.tap", etc. You can then rename the files manually in nmi menu, or LNX commander, or in Basic.



DIRECT COMMAND INPUT
********************
True, that version 1.0 can operate 20 ftp command. While there are others, that are not implemented. I avoided their implemenattion in order to save memory. Instead, you can type them using C controll key, case insensitive. Thus, you may enter eg. command SITE, upon which the server returns you all FTP commands supported by the server. Commands which need 2 channel work (communication and data channel, like LIST, RETR...), will not work in this mode. They work in the main program instead.


LOCAL FTP SERVER
****************
It is advisible to install your local server to be able to copy files from your ZX to PC and vice versa. In the package you will find FileZilla server and its interface which I find both, small and easy to install and set. Since there is no directory listing in ver 0.7. you have to know file names, and the easiest way is to have your PC screen with files open (together with the running client on ZX), and read file names you want to work with. In the server interface, you need to add a new user and password, assign a path to your drive on PC that the client will work with and enable work with files (delete, append, etc.) see the picture below. I found the latest versions incovenient to set, so I use this old version instead. But practically, you can use any local ftp server of your wish.


IDDLE TIME
**********
The client sends a NOOP command roughly every 1 minute to keep your connection alive and to prevent being kicked off by the server for inactivity. However, some servers can monitor traffic and kick you off, despite NOOP command sending.


ERROR CODES
***********
Serve mainly for my purposes, but you may encounter them, here is the list for you:

	;1=sending string error (cipsend_request routine)			...OK
	;2=error sending CWMODE AT commad					...OK
	;3=error sending CIPMUX AT command					...OK
	;7=error sending CIPCLOSE AT command (ftp upload)			...OK

	;8= module did not return SEND OK after data block sending (ftp_upl_send)..OK
	;9= error in entering passive mode (enter_passive_mode)			...OK
	;14=file not exist							...OK
	;15=disk error								...OK
	;25= module not connected to AP, the user has to set his module externally.OK

;ftp	;4= check_module_answer routine did not found the answer from DE	...OK
	;5= uploaded data not sent correctly (ftp_upl_send)			...OK
	;6= cipsend_lod routine error. Module not ready to send data for upload	...OK
	;10= error in connecting to ftp server (ftp_login)(probably wrong URL)	...OK
	;11= error in receiving ftp answer (receive_ftp_answer)			...OK
	;12= "+IPD," string not found in the incoming bytes (look_for_ipd)	...OK
	;13= FTP server did not confirm answer 225 on download attempt (ftp_download_file, or retrieve directory...OK
	;16= ABOR command not successful					...OK
	;17= upload: connection not accepted (code 150 not received)		...OK
	;18= upload: transfer not ok (code 226 not accepted)			...OK
	;19= initial check. Connected to server, not good answer to NOOP cmnd	...OK
	;20= ABOR command initiated by the user					...OK
	;21= download: files does not exist					...OK
	;22= file does not exist on ftp server					...OK
	;23= download: block of data receive error				...OK
	;24= server did not respond with "226 Transfer OK"			...OK
	;25= command sent ok, but return code other than expected		...OK
	;26= no data available in passive receive mode (routine 84)		...OK
	;27= command for create dir not accepted (create dir)
	;28=speed management: AT command not accepted						... present in the code but not used
	;29=speed management: all speeds tested, timeout, fix it in terminal-add it in the next ver... present in the code but not used
	;30=speed management: failed, probably Wifi module wrongly set,fix in terminal-add it in the next ver... present in the code but not used
	;31=user defined speed_ AT+UART_CUR command not sent			...???
	;32=user defined routine_ speed in UART not set				...???
	;33=user defined speed_ you try to set nonsence speed (ie. > 23)	...???
	;34= dir retrieve error
	;35= (look_for_ipd) 2nd error


BUGS
****
If you encounter bugs during directory reading, press R to reread directory. If you get stuck, press reset and start again. Bugs do not make any harm, they are just like any other bugs, make your life a bit harder. I continuusly work to kill'em all:)



ACKNOWLEDGEMENTS
****************
Primarily:
Busy for his couple of handful routines and advices, his idea of directory items conception, advices about find function.
Lanex for his useful hints and advices on how to write Esxdos disc routines.
LMN, SCJoe- for inspiration and knowledge.


